PATHMac OS 8 Developer Documentation > Files > Navigation Services >

Programming With Navigation Services 1.1

DISCUSSION

Register your event-handling function by passing a Universal Procedure Pointer (UPP) in the eventProc parameter of a Navigation Services function such as NavGetFile . You obtain this UPP by calling the macro NewNavEventProc and passing a pointer to your event-handling function. If you determine that the event is appropriate for your event-handling function, you can call other functions to handle custom control drawing, object filtering, or custom previews. For more information, see Creating Application-Defined Functions.

SPECIAL CONSIDERATIONS

When events involve controls, your event-handling function must respond to events only for your application-defined controls. To determine which control is affected by an event, pass the kNavCtlGetFirstControlID constant, described in Custom Control Setting Constants , in the selector parameter of the function NavCustomControl .

MyPreviewProc

Displays custom file previews. This is how your application would define its own preview function if you chose to call it MyPreviewProc :

pascal Boolean MyPreviewProc    (
                                NavCBRecPtr callBackParms,
                                void *callBackUD );

callBackParms

A pointer to a structure of type NavCBRec . Navigation Services uses this structure to provide data needed for your function to draw the preview.

callBackUD

A pointer to a value set by your application when it calls a Navigation Services function such as NavGetFile . When Navigation Services calls your preview function, the callBackUD value is passed back to your application in this parameter.

function result

A Boolean value. Your application returns true if your preview function successfully draws the custom file preview. If your preview function returns false , Navigation Services displays the preview if the file contains a valid `pnot' resource. If your preview function returns false and a `pnot' resource is not available, Navigation Services displays a blank preview area. For more information, see Drawing Custom Previews.

DISCUSSION

Register your preview function by passing the resulting Universal Procedure Pointer (UPP) in the previewProc parameter of a Navigation Services function, such as NavGetFile . You obtain this UPP by calling the function NewNavPreviewProc and passing a pointer to your preview-drawing function. When the user selects a file, Navigation Services calls your preview-drawing function. Your preview function, in turn, calls the function NavCustomControl to determine if the preview area is visible and, if so, what its dimensions are. For more information, see Drawing Custom Previews.

MyFilterProc

Determines whether file objects should be displayed in the browser list and navigation menus. This is how your application would define its own filter function if you chose to call it MyFilterProc :

pascal Boolean MyFilterProc (AEDesc* theItem,
                            void* info,
                            void *callBackUD,
                            NavFilterModes filterMode);

theItem

A pointer to an Apple event descriptor structure ( AEDesc). Navigation Services uses this structure to provide information about the object being passed to your filter function.

IMPORTANT

Always check the Apple event descriptor type before deciding if an object needs to be filtered. Never assume that objects are type 'typeFSS' , because the browser or pop-up menus may contain objects of other types. Make sure that your function only returns false if it recognizes the object. For more information, see Obtaining Object Descriptions.

info

A pointer to a structure of type NavFileOrFolderInfo . Navigation Services uses this structure to provide file or folder information about the item being passed to your filter function. This information is not valid for objects which are not HFS file objects.

callBackUD

A pointer to a value set by your application when it calls a Navigation Services function such as NavGetFile . When Navigation Services calls your filter function, the callBackUD value is passed back to your application in this parameter.

filterMode

A value representing which list of objects is currently being filtered. For a description of the constants used to represent these values, see Object Filtering Constants.

function result

A Boolean value. If your application returns true , Navigation Services displays the object. If your application returns false , Navigation Services will not display the object.

DISCUSSION

Register your filter function by passing a Universal Procedure Pointer (UPP) in the filterProc parameter of a function such as NavGetFile . You obtain this UPP by calling the macro NewNavObjectFilterProc and passing a pointer to your filter function. Navigation Services calls your filter function to determine whether a file object should be displayed in the browser list or the pop-up menus.

If you use a filter function in conjunction with built-in translation, you should provide a list of file types in the typeList parameter of a file-opening function such as NavGetFile to inform Navigation Services which document types your application can open. If you provide a list of file types in the typeList parameter, take care to ensure that your filter function does not accidentally filter out any document type described in the list. For more information, see Filtering File Objects.

SPECIAL CONSIDERATIONS

If your filter function returns a result of true , Navigation Services displays the object. This is the opposite of Standard File filter functions.

NavCustomControl

Allows your application to control various settings in Navigation Services dialog boxes.

pascal OSErr NavCustomControl (NavContext context,
                                         NavCustomControlMessages selector,
                                         void *parms );

context

A value set by your application to provide context. When Navigation Services processes your NavCustomControl call and, in turn, calls your event-handling function, you can obtain this value from the context field of the structure of type NavCBRec specified in the callBackParms parameter of your event-handling function.

selector

A value of type NavCustomControlMessage . Pass one or more of the constants representing the possible values used to control various aspects of the active dialog box. For a description of these constants, see Custom Control Setting Constants.

parms

A pointer to a configuration value. Some of the control setting constants passed in the selector parameter require that you provide an additional configuration value. For a description of which constants require configuration values, see Custom Control Setting Constants.

function result

see Result Codes for a list of result codes.

DISCUSSION

If you have provided an event-handling function and an event occurs in a Navigation Services dialog box, Navigation Services calls your event-handling function and specifies one of the constants described in Event Message Constants in the param field of the structure of type NavCBRec . Navigation Services specifies this structure in the callBackParms parameter of your event-handling function. When Navigation Services supplies the kNavCBStart constant in the param field, your application can call the NavCustomControl function and pass one of the constants described in Custom Control Setting Constants to control various aspects of the active Navigation Services dialog box. For example, your application can tell Navigation Services to sort the browser list by date by calling the NavCustomControl function and passing the kNavCtlSortBy constant in the selector parameter and a pointer to the kNavSortDateField configuration constant in the parms parameter. (Some of the NavCustomControlMessage constants do not require a corresponding configuration constant.)

SPECIAL CONSIDERATIONS

Navigation Services does not accept calls to the NavCustomControl function until an appropriate dialog box is fully initialized and displayed. Always check for the kNavCBStart constant, described in Event Message Constants , in the param field of the NavCBRec structure before calling the NavCustomControl function.

Note that your application can call the NavCustomControl function from within its event-handling function or its preview-drawing function.

SEE ALSO

Adding Custom Controls .

Handling Events .